Copsim Doc <<
Previous Next >> pjgazebo
Webots Doc
網際文件處理技術
2019 年時 Webots 的使用者手冊文件目錄, 位於 docs, 其中 doc.php 負責處理當時網站 /doc 目錄下的文件網際派送, 共有三個主要文件:
Webots Guide: https://cyberbotics.com/doc/guide/index
Webots Reference Manual: https://cyberbotics.com/doc/reference/index
Webots for Automobiles: https://cyberbotics.com/doc/automobile/index
意即, 2019 年時 Webots 的網頁採用 php 程式, WWW 伺服器採用 Apache, 而操作系統則使用 Ubuntu. (註: 目前的 docs 架構已經與當時完全不同).
從當年的 local_exporter.py 也可以發現, Webots 建議在近端使用 doc 目錄下文件的方式為, 利用 local_exporter.py 從官方網站下載 index.html 與 dependencies 目錄中所需的 Javascript, 然後再透過 index.html 導引各 Javascript 程式, 從 guide, reference 與 automobile 目錄中, 將 markdown 格式文件動態轉為 html.
利用 Markdown 與 Javascript 處理遠端與近端文件的好處是, 文件管理人員可以採用各式合用的文字編輯器管理所有 Markdown 檔案, 且各版本間的內容可以納入分散式版次管理系統, 不僅能夠多人非同步協同, 且透過資料庫中版次的內容擷取, 可以在同一網站中透過網際 URL 版次變數的宣告而擷取不同版本的文件.
例如: https://www.cyberbotics.com/doc/guide/page?version=R2019a 可以取得倉儲中 tag 為 R2019a 版次的 Webots guide 文件內容.
而 https://www.cyberbotics.com/doc/guide/page?version=R2019a-rev1 則是 R2019a-rev1 版次的文件內容.
以上處理網際文件的技術, 除了能夠將軟體套件的手冊納入分散式版次管理系統 (如 Git 或 Fossil SCM) 之外, 還能讓之後的多語系文件, 以不同的 Markdown 文件目錄儲存, 然後在主文件連結中提供不同語系 Markdown 文件所在目錄即可, 例如:
/doc/guide_zh-TW 指向中文正體文件目錄, 而 /doc/guide_zh-CN 則指向中文簡體文件目錄等, 各語系文件可以採用分散式版次管理的流程, 以非同步協同方式自行管理維護不同 Webots 套件的各種技術文件.
KMOL 能夠從 Webots 技術文件處理流程中學到甚麼?
這應該是一個不錯的 4+1 碩士題目:-)
Webots 早在 2008-2009 年間, 就已經 透過 https://en.wikibooks.org/wiki/Cyberbotics%27_Robot_Curriculum 完成兩本導引課程文件的建構:
Cyberbotics Robot Curriculum.pdf
Design and Assessment of a Robot Curriculum based on the E-puck Robot and Webots.pdf
假如當年在編輯處理這些資料的過程, 能夠採用 Git (Git on Wikipedia) 或 Fossil SCM (Fossil on Wikipedia) 分散式版次管理系統, 現在應該就不只留下 Wikibooks 或 pdf 等零散資料, 而是能夠讓隨後的學員回到當時的網際技術與文件格式情境, 充分了解改版與內容取捨細節, 以便更近一步掌握過去十年各種電腦與網路技術推陳出新的脈絡, 作為之後判斷與持續改進的依據.
Copsim Doc <<
Previous Next >> pjgazebo